home *** CD-ROM | disk | FTP | other *** search
/ Ham Radio 2000 / Ham Radio 2000.iso / ham2000 / satellit / ao27tlm / ao27tlm.doc < prev    next >
Text File  |  1993-12-03  |  11KB  |  250 lines
  1.  
  2.                            AO27TLM.EXE V 1.0  
  3.  
  4.                           By John Teller, N4NUN
  5.  
  6.   (C) Copyright 1993 by the Amateur Radio Research and Development Co.
  7.  
  8.      AO27TLM is a program which processes the telemetry data transmitted
  9. by the AO-27 satellite.  Although this satellite is based on the AMSAT
  10. microsats, the telemetry output by this satellite is unlike that output
  11. by the other microsats.  This satellite is sponsored in part by the
  12. Amateur Radio Research and Development Co. (AMRAD) and built at
  13. Interferometrics, Inc. in Tyson's Corner, VA.  The primary payload of
  14. this satellite is commercial and is known as EYESAT.
  15.  
  16.      This software is solely the property of AMRAD and is distributed free
  17. to noncommercial users, who may copy and distribute this program at will
  18. providing this documentation file accompanies the AO27TLM executable
  19. file, and that the contents of either file are not modified in any way.
  20.  
  21.      Please forward any comments, bug reports or whatever to:
  22.  
  23.                                   AMRAD
  24.                             P.O. Drawer 6148
  25.                              McLean VA 22106
  26.  
  27.              or leave mail on the AMRAD BBS (703) 734-1387.
  28.  
  29.  
  30. AO27TLM FEATURES
  31. ================
  32.  
  33. 1)   This program can display telemetry data as received directly from
  34.      the AO-27 satellite through a standard TAPR TNC2 or clone (such as
  35.      an MFJ 1270) capable of operating in KISS mode.
  36. 2)   Telemetry data can be logged to disk in either raw KISS format or
  37.      in a time-stamped ASCII Hex file.
  38. 3)   Logged telemetry files may be replayed through the software for
  39.      viewing after a pass.
  40. 4)   Logged telemetry files can be converted to a comma (or other
  41.      character) separated file for use with a data base or with plotting
  42.      software.
  43. 5)   Whole Orbit Data (WOD) can be output to a comma (or other
  44.      character) separated file.
  45. 6)   Since the list of channels in the WOD frames is subject to change,
  46.      the software has the capability of being updated remotely with a
  47.      list transmitted by the AO-27 satellite.
  48. 7)   Any changes to the coefficient list can be updated remotely with
  49.      data transmitted by the AO-27 satellite.
  50.  
  51.  
  52. IMPORTANT FILES
  53. ===============
  54.  
  55. AO27TLM.EXE -- The executable.
  56. AO27TLM.DOC -- This file.
  57. EYECOEF     -- Contains the coefficient values for the various telemetry
  58.                channels.  This file is formatted mostly as are the AMSAT
  59.                coefficient files, the only difference is that channel ff
  60.                is reserved for use as the coefficient file version.
  61. EYELIMS     -- This file contains the limits which will cause data to be
  62.                displayed in a color other than green when exceeded. 
  63.                Again this file is organized like the equivalent AMSAT
  64.                limits files.
  65. EYEWOD      -- This file contains the list of telemetry channels
  66.                included in the WOD frames.
  67. LOG2KSS.EXE -- A utility to convert an ASCII Hex file to a raw KISS
  68.                file, which takes up less than half the space of the
  69.                ASCII file.
  70.  
  71.  
  72. HOW TO USE AO27TLM
  73. ==================
  74.  
  75.      In its simplest form AO27TLM will examine the stream of KISS data
  76. emanating from a TNC2 in KISS mode connected to COM1: for telemetry,
  77. message, up time and coefficient and WOD list update frames.  All
  78. received data is logged in its raw KISS format to a log file with a name
  79. generated by the current PC time when the file was first opened.  Any
  80. telemetry, message and up time frames are displayed on the screen as
  81. they are received.  In order to use AO27TLM in this mode it is only
  82. necessary to connect a TNC2 set to 4800 baud, 8 bits, no parity to COM1
  83. of your PC.  When AO27TLM is run, the coefficients will be loaded from
  84. the file EYECOEF.  If the file EYELIMS exists, it will be read and any
  85. limits it contains will be used whenever a telemetry frame is displayed. 
  86. After a pass is complete you need only to press the <Esc> key to quit
  87. out of AO27TLM.  Do not shut off the computer without escaping, since
  88. any log files will not be closed properly and data loss may result.
  89.  
  90.      AO27TLM may also be used to review collected telemetry at a later
  91. date.  To do this you need only enter "AO27TLM logfile.KSS" at the DOS
  92. prompt.  Of course logfile is the name of the file you wish to review. 
  93. At this time you may also generate a comma separated file of the
  94. telemetry values to feed into a data base or other program.  To do this
  95. enter "AO27TLM logfile.KSS /OD" at the DOS prompt.  This will open the
  96. KISS file with the name "logfile", and create a comma separated file
  97. with a name generated by the current PC time.  In order to write to a
  98. file other than that with the default name, enter "AO27TLM logfile.KSS
  99. /OD /Ldatafile.DAT" at the DOS prompt.  This will write any output data
  100. to the file "datafile.DAT".  If that file already exists, any new data
  101. will be appended to it.  See the next section for more information.
  102.  
  103.  
  104. COMMAND LINE ARGUMENTS
  105. ======================
  106.  
  107. /COMX     Use a serial port other than COM1 to communicate with the KISS
  108.           TNC.  Values supported are COM1, COM2, COM3 and COM4.  
  109. /RXXXX    Use a serial port bit rate other than 4800 baud.  Any standard
  110.           speed from 300 to 19200 is supported.
  111. /L+       Log received data to a raw binary KISS file (file name is
  112.           YJJJHHMM.KSS).  This is the default logging state.
  113. /L-       This option stops any data logging.
  114. /M        Force monochrome display.  This can be used with PC's that
  115.           have a CGA board connected to a composite monochrome monitor. 
  116.           PCs with a standard MDA board will automatically be placed in
  117.           this mode.
  118. /OD,K,T   Output file type: Data, Kiss or Time stamped.  The default for
  119.           this is /OK, which will produce a raw binary KISS file.  If an
  120.           ASCII hex file is desired you may use the /OT command.  The
  121.           /OD command, used to output a comma separated data file, can
  122.           only be used when the input is from a previously logged file.
  123. /SXX      Data separator char, where XX = ASCII code of the char in hex. 
  124.           the default is /S2C (character 2C is a comma).  To use a tab
  125.           as the separator, you would enter /S09 and so on.
  126. /Bfname   This command can be used to load the limits (Boundaries) from
  127.           a file other than EYELIMS. fname is the name of the desired
  128.           file.
  129. /Efname   This command can be used to load the coEfficients from a file
  130.           other than EYECOEF.  fname is the name of the desired file.
  131. /Dfname   This command can be used to load the WOD list from a file
  132.           other than EYEWOD.  fname is the name of the desired file.
  133. /Lfname   Will out Log data to a file with the given name.  It is also
  134.           used when converting data to the comma separated file.  In
  135.           that mode it defines the name of the output data file.
  136. /Wfname   This command can be used to cause AO27TLM to write any WOD
  137.           frames encountered in the data stream (either from a TNC or
  138.           from a file) to an output file with the given name.  If the
  139.           file already exists, the new data will be appended to it.
  140.  
  141. Default command line is:  AO27TLM /COM1 /R4800 /L+ /OK
  142.  
  143.  
  144. INPUT FILE STRUCTURES
  145. =====================
  146.  
  147. EYECOEF:
  148.  
  149.      Each line contains the coefficients for one channel.
  150.  
  151. Byte No.  Description
  152. --------  -----------
  153.  0 -  1   The channel number in Hexadecimal, only channels 00-31 (0-49
  154.           decimal) are recognized.  Channel ff is reserved to set the
  155.           version of the current EYECOEF file.
  156.  2 -  5   Space characters.
  157.  6 - 20   The channel label.
  158. 21 - 32   Coefficient A.
  159.      33   Space.
  160. 34 - 45   Coefficient B.
  161.      46   Space.
  162. 47 - 57   Coefficient C.
  163.      58   Space.
  164. 59 - 64   Units label.
  165.      65   Carriage return.
  166.      66   Line feed.
  167.  
  168. NOTE: AO27TLM is very forgiving of the positions of the coefficients
  169. relative to each other.  The only element with a critical length is the
  170. channel label, which must have 15 characters.
  171.  
  172. EYELIMS
  173.  
  174.      Each line contains the upper and lower limits for one channel.  The
  175. positions of the three elements in each line are not critical, so long
  176. as the channel number is in hexadecimal, and is followed by the lower
  177. limit, then by the upper limit.  Each line is terminated with a <CR><LF>
  178. pair.  Example:
  179.  
  180. 1a, 123.0, 321.0<CR><LF>
  181.  
  182. This means that channel 1a (20 decimal) has a low limit of 123.0 and a
  183. high limit of 321.0.
  184.  
  185.  
  186. OUTPUT FILE STRUCTURES
  187. ======================
  188.  
  189.      For the following file names the following name is used:  YJJJHHMM. 
  190. Y is the last digit of the year (3 for 93), JJJ is the julian day (001
  191. for Jan 1), HH is the hour of the day (00-23) and MM is the minute (00-
  192. 59).  The default file name is established when the file is first opened
  193. and depends on the current PC time.  XT and PC users take note:  Do set
  194. your DOS clock manually if you don't have a battery backed clock
  195. installed in your system!
  196.  
  197. YJJJHHMM.LOG - Received data output as ASCII Hex data.
  198. YJJJHHMM.KSS - Received data output as a raw binary KISS file.
  199. YJJJHHMM.DAT - A comma separated data file containing the decoded
  200.                telemetry.
  201. YJJJHHMM.WOD - Whole Orbit Data extracted from the telemetry stream.
  202.  
  203. LOG file structure:
  204.  
  205. [Fri Dec 03 12:00:00 1993] DD DD DD ... DD DD DD<CR><LF>
  206.  
  207.      The time stamp between the brackets is the PC's time when the frame
  208. was received.  The data after that is in an ASCII representation of
  209. hexadecimal binary data.  The valid characters here are 0, 1, 2, 3, 4,
  210. 5, 6, 7, 8, 9, a, b, c, d, e and f.  The <CR> and <LF> indicate a
  211. carriage return and line feed character, respectively.
  212.  
  213. DAT file structure:
  214.  
  215. Fri Dec 03 12:00:00 1993,Tlm_Time,CH,Val.NNN,CH,Val.NNN...<CR><LF>
  216.  
  217.      The time stamp before the first comma is the ASCII equivalent of
  218. the Unix-type time taken when the satellite performed the last telemetry
  219. collection.  Tlm_Time is a long count of seconds since Jan 1, 1970
  220. 00:00:00 and is the time of the last telemetry collection.  CH is the
  221. telemetry channel, Val.NNN is a floating point value.  The last two
  222. elements are repeated for the various telemetry channels.  After the
  223. list is complete a <CR><LF> pair is appended.
  224.  
  225. WOD file structure:
  226.  
  227. Fri Dec 03 12:00:00 1993,Tlm_Time,Ver,Val.NNN,Val.NNN...<CR><LF>
  228.  
  229. Ver is the version of the WOD list used to define the elements in a WOD
  230. frame.  If this value does not agree with that in EYEWOD, the output WOD
  231. file could contain bogus data.
  232.  
  233.  
  234. REFERENCES
  235. ==========
  236.  
  237. Smith, G. Gould, WA4SXM, "Decoding Telemetry from the Amateur Satellites",
  238.      AMSAT-NA P.O. Box 27 Washington DC 20044
  239.  
  240.  
  241. ACKNOWLEDGEMENTS
  242. ================
  243.  
  244.      Special Thanks to Mark Kanawati, N4TPY and Mike Wyrick, N4USI who
  245. made this project possible with their beta-testing and design help.
  246.  
  247.  
  248.                           **** Join AMRAD! ****
  249.  
  250.